home *** CD-ROM | disk | FTP | other *** search
/ HyperLib 1997 Winter - Disc 1 / HYPERLIB-1997-Winter-CD1.ISO.7z / HYPERLIB-1997-Winter-CD1.ISO / オンラインウェア / MLT / XEarth for Mac 1.0.1.sit / XEarth for Mac 1.0.1 / XEarth for Mac documentation < prev    next >
Text File  |  1996-07-12  |  15KB  |  238 lines
  1.                       XEarth for Mac 1.0.1
  2.                                                            by Johan Lindvall.
  3.  
  4. ﾊ
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                                                                      A picture generated by XEarth for Mac
  13.  
  14. Introduction
  15. XEarth for Mac displays shaded images of the Earth. It is based on the UNIX version of XEarth by Kirk Lauritz Johnson. I hesitate to call this a port, because I have worked a lot on converting it to the Mac and giving it new features. Still, it is freeware, and you are encouraged to copy is as long as you distribute it in its original package.
  16.  
  17. Requirements
  18. XEarth for Mac requires a Macintosh with a FPU. That is either a Power Macintosh or an "old" Macintosh with a FPU. Atleast system 7.0 or higher is required (it has only been tested with 7.5 so it may not work on older systems)
  19.  
  20. Installation instructions
  21. XEarth for Mac consists of two parts which are both fat binaries; a system extension called XEarth INIT and the application called XEarth for Mac. The system extension is used by XEarth for Mac to draw in the Finder desktop. If you want XEarth to draw in the Finder desktop install this system extension by dragging it onto the active system folder.
  22.  
  23. The Menus
  24. XEarth for Mac has four menus: the Apple, File, Edit, and Windows menus.
  25.  
  26. The Apple menu
  27. The "About XEarthﾉ" item displays a window with some information about the current version of XEarth for Mac.
  28.  
  29. The File menu
  30. New Earth Window creates a new window, a default setup and displays the Earth in the window.
  31.  
  32. Close Window closes the frontmost window. The frontmost window is indicated in the window menu with a checkmark.
  33.  
  34. Open Setup works as New Earth Window, except that the setup is selected via a open file dialog.
  35.  
  36. Save Setup saves the setup of the frontmost window to a disk file.
  37.  
  38. Edit Setup brings up the edit setup dialog, which is described below.
  39.  
  40. Obscure Cursor hides the cursor (the cursor becomes visible when it is moved or the button is clicked). This is useful if the frontmost window is a full screen window.
  41.  
  42. Preferences brings up the preferences dialog as shown below:
  43.  
  44. ﾊ
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66. If "Open first file in background" is selected, XEarth for Mac will put itself in the background if it was started via a Finder open of a previously saved setup. This can be useful if you put a setup (or an alias of a setup) in the Startup Items folder. At startup, XEarth for Mac will open the setup and then bring the Finder to the foreground, as it normally is.
  67.  
  68. If "Warn about missing INIT" is checked, XEarth for Mac will give you a notice everytime it starts and the system extension "XEarth INIT" is not installed.
  69.  
  70. If the item "Use deep bitmaps" is check, XEarth for Mac will render the image of the Earth in a 32 bits per pixel buffer. This item must be check if you want to export the rendered images.
  71.  
  72. Check "Use fast bitmaps" to have the image of the Earth stored or rendered (depending upon if "Use deep bitmaps" is check or not)  in a bitmap optimized for the main screen. If neither "Use deep bitmaps" nor "Use fast bitmaps" is checked, XEarth will act as if "Use fast bitmaps" was checked.
  73.  
  74. If "Release CPU" is checked, XEarth will give time to other applications after the amount of ticks (one tick is approximately 1/60th of a second) specified to the right of the button.
  75.  
  76. Finally, if "Use cities from Map Control Panel" is checked, XEarth will use the cities from the Map Control Panel as markers (see below).
  77.  
  78. The Quit item in the File Menu quits the application.
  79.  
  80. The Edit Menu
  81. The items in the Edit Menu are all self-explainatory so I will not describe them here. They are only used in the setup dialog.
  82.  
  83. The Window Menu
  84. The Window Menu is a list of all the currently open the windows. The frontmost window is indicated by a checkmark. Selecting a window in the menu brings it to the front.
  85.  
  86. The Setup Dialog
  87. The Setup dialog is the core of XEarth for Mac. The default setup looks like this in the setup dialog:
  88.  
  89. ﾊ
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124. Projection type
  125. The radio buttons Mercator and Orthographic specifies the projection type XEarth should use. 
  126.  
  127. Viewing position
  128. The viewing position can be one of four types; Fixed, Sun relative, Orbit or Random.
  129.  
  130. If fixed is selected the viewing position will be determined by the values entered in the latitude and longitude fields to the right of the Fixed button. Positive and negative values of latitude correspond to positions north and south of the equator, respectively. Positive and negative values of longitude correspond to positions east and west of Greenwich, respectively.
  131.  
  132. There is a popup-menu to the right of the fixed viewing position longitude field. When fixed viewing position is selected, you can use the popup-menu to select a marker and have its coordinates entered in the latitude and longitude fields.
  133.  
  134. If sun relative is selected the viewing position will be determined by the caclulated position of the sun (see Sun position, below) offset by the values entered in the latitude and longitude fields to the right of the Sun relative button.
  135.  
  136. If orbit is selected the two values in the fields to the right of the orbit button will be interpreted as numerical values indicating the period (in seconds, from 1 to 99999) and orbital inclination (in decimal degrees) of a simple circular orbit; the viewing position follows this orbit. Astute readers will surely note that these parameters are not sufficient to uniquely specify a single circular orbit. This problem is solved by limiting the space of possible orbits to those positioned over 0 degrees latitude, 0 degrees longitude at time zero (the Un*x epoch - Jan 1 1970 00.00.00).
  137.  
  138. If random is selected the viewing position will be selected at random each time an update occurs.
  139.  
  140. Lastly, if rotation is selected, the viewing position will be rotated such that the north is not "straight up".  Positive values in the field to the right of rotation rotate the rendered image counterclockwise; negative values rotate the rendered image clockwise.
  141.  
  142. Sun Position
  143. If the sun positition is choosen as time dependent XEarth calculates the actual position of the Sun and updates this position with the progression of time (see Time, below).
  144.  
  145. A fixed sun position places the sun at a position where it is directly overhead at the longitude and latitude in the fields to the right of the fixed button. As an alternative, you can use the popup-menu to select a marker and have its coordinates entered in the latitude and longitude fields.
  146.  
  147. Display Mode
  148. XEarth for Mac can display the image of the Earth in three different ways; in a regular window, in a fullscreen window, or in the finder desktop.
  149.  
  150. If the window is to be displayed as a normal window, the fields width and height determine the widht and height of the image rendered by XEarth. The values enterd in the fields can range from 1 to 4000, inclusive.
  151.  
  152. If the Full Screen button is checked, XEarth for Mac will use the full screen (including the menubar) to display its image. The image size will be equal to the size of the screen. The button will be grayed out when there already is another window displaying its image on the full screen.
  153.  
  154. If the Finder Desktop button is selected, XEarth for Mac uses the Finder desktop window to draw in. The image width will be the screen size and the image height will be the screen height minus the menu bar height. The button will be grayed out if the system extension XEarth INIT is not installed or when there already is another image displayed in the Finder desktop.
  155.  
  156. Time
  157. If the button Start UTC is selected, the time used for XEarth calculations will start at the time specified in the fields to the right of the button. The time, as all time in XEarth for Mac, is specified in UTC(GMT). You can not enter a year value before 1990 or after 2040.
  158.  
  159. If Start Now is selected, the time will start "now", i.e. when the setup dialog is closed via the OK button or when the setup, if saved, is loaded from disk.
  160.  
  161. When the Update button is checked, XEarth will update its internal time after the number of seconds specified in the field to the right of the update button elapse.  Everytime the internal time becomes updated the Earth image will be recalculated. The internal time can be sped up or slowed down by the factor entered in the timewarp field.
  162.  
  163. Magnification
  164. Magnification specifies the factor of magnification of the displayed image
  165.  
  166. Shift x and Shift y specify that the center of the rendered Earth image should be shifted by some amount from the center of the image. Shift x is interpreted as an pixel offset in the x direction and Shift y is an offset in the y direction.
  167.  
  168. Shading
  169. The shading button enables/disables shading. When shading is enabled, the surface of the Earth is shaded according to the current position of the Sun (and the values provided for day, night, and terminator, see below). When shading is disabled, flat colors (green and blue) are used to render land and water.
  170.  
  171. The day field specifies the brightness that should be used to shade the day side of the Earth when shading is enabled. This value should be an integer between 0 and 100, inclusive, where 0 indicates total darkness and 100 indicates total illumination.
  172.  
  173. The night field specifies the brightness that should be used to shade the night side of the Earth when shading is enabled. This value is interpreted as the day value.
  174.  
  175. The terminator field specifies the shading discontinuity at the terminator (day/night line). This value should be an integer between 0 and 100, inclusive. A value of x indicates that the shading should immediately jump x percent of the difference between day and night shading values when crossing from the night side to the day side of the terminator. Thus a value of 0 indicates no discontinuity, and a value of 100 yields a maximal discontinuity (such that the entire day side of the earth is shaded with the day shading value).
  176.  
  177. Labels & Markers
  178. The check-button Label  enables/disables labeling. If labeling is enabled a label that indicates the current (internal) date and time and current viewing and sun positions will be drawn in the lower right corner of the image.
  179.  
  180. The check-button markers enable/disable markers. If markers are enabled small red circles and text labels indicating the location of interesting places on the Earth's surface will be displayed. These places are specified in the resource 'mrkr' 128.
  181.  
  182. Stars
  183. The check-button stars enables/disables stars. If stars are enabled, the black background of "space" is filled with a random pattern of "stars" (individual white pixels). The fraction of background pixels that are turned into stars can be controlled with the Frequency field (see below).
  184.  
  185. The field frequency sets the density of the random star pattern (see stars, above); frequency indicates the fraction of background pixels that should be turned into "stars".
  186.  
  187. The field bigstars specifies the percentage of double-width stars (see stars, above); by default, all stars are a single pixel, but this option can be used to create some stars that are composed of two horizontal pixels.  This provides a slightly less uniform look to the "night sky".
  188.  
  189. Grid
  190. The check-button grid enables/disables the display of a longitude/latitude grid on the Earth's surface. The spacing of major grid lines and dots between major grid lines can be controlled with the Line Spacing and Dot Spacing fields (see below).
  191.  
  192. The field Line Spacing specifies the spacing of major grid lines if grid display (see grid, above) is enabled; major grid lines are drawn with a 90/Line Spacing degree spacing.
  193.  
  194. The field Dot Spacing specifies the spacing  of dots along major grid lines if grid display (see grid, above) is enabled. Along the equator and lines of longitude, grid dots are drawn with a 90/(Line Spacing x Dot Spacing) degree spacing. The spacing of grid dots along parallels (lines of latitude) other than the equator is adjusted to keep the surface distance between grid dots approximately constant.
  195.  
  196. The Buttons
  197. Pressing OK or Cancel in the setup dialog results in the expected; the changes to the setup are either accepted or rejected. Pressing Revert reverts the items in the dialog to the last accepted state (or the default state, if the OK button has not been pressed for the displayed setup). The Default button sets the items in the dialog to the previously read default setup. The default setup is builtin, but if you want to have another setup as the default, then it is possible to save a setup file named default in the same directory as the XEarth for Mac application. This setup will be used as the default the next time XEarth for Mac is started.
  198.  
  199. Version history
  200. 27/4 1995:
  201. Initial release as version 0.9.
  202.  
  203. 3/10 1995:
  204. Version 0.92 released. The program is fat, it now runs on a Power Macintosh and a Macintosh with a FPU-processor. All time is now entered/displayed in UTC. Some bugs were fixed. Save/Open setup was implemented. The error handling is a bit smarter. The program is rewritten in C++, and adding new features should be much easier.
  205.  
  206. 24/6 1996:
  207. Version 1.0 released. Another complete rewrite from scratch (sigh). Changes from XEarth 1.0 UNIX now incorporated. The application should be a bit faster, especially the PowerPC-version. Finder Desktop drawing implemented.
  208.  
  209. 12/7 1996:
  210. Version 1.0.1 released.
  211. The XEarth engine has been optimized and is now 15-20 % faster.
  212. Bugs fixed: fixed a bug which could cause random crashes. Open setup dialog now works. Finder desktop drawing should work with multiple monitors. Works correctly when the computer is waken up from sleep.
  213. Features added: Can render in bitmaps flatter than 32 bits. Can now multitask properly. Optionally uses cities from the Map Control Panel.
  214. Known bugs: Finder desktop drawing does not work on System 7.1
  215.  
  216. Future ideas
  217. better handling of errors
  218. a nice window-manager
  219. make it Applescriptable
  220. exporting of QuickTime movies
  221.  
  222. Author's address
  223. Send comments, bug reports or whatever you like to my email address:
  224. d2linjo@dtek.chalmers.se
  225. Visit the XEarth for Mac page on WWW at http://www.dtek.chalmers.se/~d2linjo/mac_xearth.html
  226. Kirk Lauritz Johnson's e-mail address is tuna@cs.colorado.edu
  227.  
  228. Copyrights & disclaimer
  229. XEarth for Mac 1.0.1 is Copyright ｩ 1995-6 Johan Lindvall
  230. XEarth for Mac 1.0.1 is based on XEarth 1.0 for UNIX which is Copyright ｩ  1989-90, 1993-95 Kirk Lauritz Johnson.
  231. The PowerPC version is linked with libmoto, which is Copyright ｩ Motorola
  232.  
  233. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.
  234.  
  235. THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  236.  
  237. -
  238. A lot of the above documentation was taken from the XEarth UNIX man-page